# Arpezia Design System v2 Arpezia is a practice platform for brass students (age 8 through adult): guided routines, a library of exercises, method-book lessons, songs, recordings, and teacher assignments. This system covers the **web app** (Vue frontend), the **marketing website**, a **slide template**, an **email template**, and **social/print assets**. ## Sources - `uploads/README.md` — staging notes with all decisions (scope, inventory, conflict rule, brand facts, tokens). - `uploads/reference/library-handoff-README.md` — component-level spec for the Library redesign (v3). The authority for values. - `uploads/reference/Library Redesign v3.dc.html` — 24 live artboards (4 tabs × Normal/Simple × desktop/tablet/phone). - `uploads/reference/APZ_Logo_Mocks.pdf` — logo in situ. - `uploads/assets/` — logo SVG/PNG set, Avant Garde BT TTFs (Book, Demi, Demi Oblique), original pencil sketch (`assets/logos/sketch/the-idea.png`). - Source repo: `github.com/Arpezia/arpezia-platform` (main), `frontend/src`. Not connected in this project. **Conflict rule:** the Library mockups win; repo `style.css` / `themes/index.js` differences are "repo diffs", not adopted. ## Content fundamentals Full guides: `guidelines/voice.html` (how Arpezia sounds) and `guidelines/style.html` (how Arpezia writes it down: 32 checkable rules, word list, checklist). The style guide wins on punctuation, capitals, numbers, notation, and vocabulary. - **Voice:** warm, patient, explains why. The best private teacher you ever had. "Your trumpet is waiting. Today’s plan takes about 23 minutes." - **Person:** "you" for the player; "we" only when Arpezia is doing something; Arpezia by name in privacy and billing. - **Reading level:** grade 4 to 5 wherever a child might read; up to 8 for parents, teachers, schools. - **Casing and style:** sentence case; American English; Oxford comma; no em or en dashes; ranges use “to”; curly quotes; “and” not “&”; buttons start with a verb; uppercase only via `text-transform`. Never type in all caps. - **One word per thing:** the style guide word list. player (not user), teacher (not instructor), parent or guardian, free trial (not free week), sign in (not log in), The Musicians’ Room, choose/start/open (not click/tap/select). Capitalize named tools and tiers (Tuner, Metronome, Tone Generator, Tone Meter, Plus, Studio, Institution); lowercase kinds of content (routine, exercise, lesson, song, plan, goal, badge, streak). The four free tools always in that order. - **Numbers and music:** digits for every count; round at the screen; “23 minutes” in sentences, “min” only in pills; “beats per minute” first, then BPM (never bpm); notes in scientific pitch with real accidentals (F♯3, B♭ trumpet, C4 is middle C); ranges with “to” (G4 to C6); dates, times, and money through the formatters. - **Exclamation marks:** one per screen at most, only for a real achievement. Never in errors, billing, privacy, consent. - **Errors:** what happened, likely reason, one fix. No "Oops," no apology filler, no engineering words. - **Celebrate what is real:** nod (every session), cheer (milestone, one exclamation, skill + number), moment (rare). No currencies, no loss threats. - **Claims:** "built on" / "designed around" with a citation; never "proven" or "guaranteed." - **Emoji:** none in the app or website. Social pending (open question). - **Simple mode** copy is a question: "What do you want to work on?" ## Visual foundations - **Palette.** Midnight Navy `#071a35` owns the header; a step lighter `#0e2747` owns the subnav and every dark card. Canvas is near-white `#f4f6f8`, surfaces pure white. Teal `#22c7c7` is the single accent (active nav, primary buttons, progress, checked states); applied-filter chips are a lightened Midnight Navy `#4a6a9c` with white text; on light backgrounds teal text darkens to `#0c6f6f`. Copper is reserved for the one "primary attribute" pill per card (minutes/tempo/exercises/bars): `#a8531c` as text, `#c96a2a` as fill or large type. Gold `#d4af37` only for the favorite star fill (outline `#b8860b`). Levels are Beginner green `#237a58`, Intermediate copper `#a8531c`, Advanced violet `#5b52c9`, each with a pastel tint. Max two dark values per screen; everything else is white on near-white. - **Type.** Two use cases. Print and PDF (read-only): Avant Garde Demi BT for headings, Avant Garde Demi Oblique BT when a heading needs to be oblique, Figtree for body. Digital (app, web, email, editable files): Outfit (500–600) for headings and nav, Figtree (400–800) for body, both falling back to Arial. The wordmark is lowercase Avant Garde Book BT, always as logo files. Avant Garde may be embedded only in read-only documents. Scale: 11 kickers, 12 meta, 13 body, 14 inputs, 15–17 card titles, 21–24 headings, 30 hero, all headings at 600. Heading weight is 600 across the scale, including the hero; go heavier only with a stated reason (a single numeral, a poster). Headings track -.01em (-.015em at 30px). Kickers track .1em, labels .08em. - **Spacing.** 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 28, 40. Card padding 16/16/14; main padding 22/28 (Simple: 28/40). Grid gaps 12–16. - **Radii.** 4 checkbox · 7 tab · 8 row · 10 button/input · 12 large button · 14 card · 18–20 Simple card/hero · 999 pills. - **Cards.** White, 1px `rgba(7,26,53,.1)` border, radius 14, shadow `0 1px 2px rgba(7,26,53,.04)`. Hover: border `.2`, shadow `0 4px 14px rgba(7,26,53,.08)`. Dark cards are `#0e2747` with no border. No left-border accents, no gradients. - **Borders.** Hairline `.08` (sidebar divider, unselected tile), default `.10` (cards), strong `.14` (inputs, secondary pills). On navy: `rgba(245,247,250,.18)`. - **Backgrounds.** Flat color only. No photography in the app; no textures, no gradients, no blur. Marketing may use the navy as a full-bleed hero with white logo. Every marketing footer is Midnight Navy with the white lockup and nav-text grey copy. - **Motion.** 120ms ease-out on color/border for hover only. No other animation, no bounces, no fades. - **States.** Hover: border darkens / text lightens on navy. Press: no shrink; darker fill. Focus: `:focus-visible` double ring, 2px white + 2px navy-2 on light (`--focus-ring`), 2px navy + 2px teal on dark (`--focus-ring-on-dark`). Disabled: 60% opacity + `aria-disabled`. Selected: teal border (2px on tiles), teal fill on checkbox/switch with navy check/knob. - **Progress.** 4px bars (6px in Simple), track `#cfd6e0` (on navy `rgba(245,247,250,.15)`), fill `#1aa9a9` (teal darkened to 3:1 against the track). Always `role=progressbar` with `aria-valuenow`. - **Layout.** Fixed 58px header (54 phone) + 44px subnav, both navy. Desktop app grid `232px | 1fr`. Tablet collapses filters into a Filters button + right sheet; phone into a bottom sheet with 40×4 drag handle. All targets ≥44px in Simple mode and on phone. - **Grids.** Never hard-code `repeat(N, 1fr)`. Use `repeat(auto-fit, minmax(min(, 100%), 1fr))` so cards wrap onto new rows; floors: 150 stat tiles/goal tiles, 200 House cards, 220–260 item cards, 300–340 heroes and wide cards. The 7-column calendar is the one fixed grid. - **Density modes.** Normal (dense catalog: facets, sort, chips, 3-col cards) and Simple (larger type, six goal tiles, one big action per card). Same anatomy, one toggle. ## Accessibility Target: WCAG 2.2 AA. Verified ratios live in the token comments. - **Text colors.** Muted `#5f7291` (4.9:1 white, 4.5:1 canvas) is the floor for any text; `--apz-muted-decor #7d8ea8` is for non-text only. Copper text is `--apz-copper-text #a8531c` (5.4:1); the brighter `--apz-copper` is for fills and ≥18px. Beginner green is `#237a58`. Teal text is `#0c6f6f` (5.4:1 on teal tint). Status colors are `--status-good/warn/bad` (all ≥4.5:1 on canvas). - **Type floor.** 11px minimum (kickers, pills, facet headings); 12px for meta. Uppercase via `text-transform`, not typed capitals. - **Non-text.** Unchecked borders and inputs use `--apz-inactive / --apz-border-input #8d9db3`; progress track `#cfd6e0`. Selected/active states never rely on color alone (aria-pressed, aria-current, check glyph, weight change). - **Focus.** Every focusable element shows the double ring; `outline:none` is only ever paired with `box-shadow: var(--focus-ring)`. Add class `apz-on-dark` (or `data-on-dark`) on navy containers to switch to the teal ring. - **Semantics baked into components.** Checkbox/Radio/Switch wrap a visually hidden native input (`role=switch` on Switch). Tabs: roving tabindex + arrow keys. Dialog: `aria-modal`, focus moves in, Tab is trapped, Escape closes, focus returns. Tooltip shows on focus and Escape hides it. Tag remove is a real button with a spoken label. GoalTile exposes `aria-pressed`. ProgressRow and MetricCard meters are `progressbar`s; SessionBar mic level is a `meter` with a live status. Heatmap is `role=img` with a summary. DataTable has `scope=col` and focusable rows. LevelBadge prefixes "Level:" for screen readers. - **Landmarks.** App shell: `
`, `